<!DOCTYPE html>

<html lang="en" data-content_root="../../">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />

    <title>Markdown processing within tutorials &#8212; Pytch  documentation</title>
    <link rel="stylesheet" type="text/css" href="../../_static/pygments.css?v=03e43079" />
    <link rel="stylesheet" type="text/css" href="../../_static/classic.css?v=36340f97" />
    <link rel="stylesheet" type="text/css" href="../../_static/css/pytch-classic.css?v=0321735e" />
    
    <script src="../../_static/documentation_options.js?v=7f41d439"></script>
    <script src="../../_static/doctools.js?v=9bcbadda"></script>
    <script src="../../_static/sphinx_highlight.js?v=dc90522c"></script>
    
    <link rel="icon" href="../../_static/favicon.ico"/>
    <link rel="author" title="About these documents" href="../../about.html" />
    <link rel="index" title="Index" href="../../genindex.html" />
    <link rel="search" title="Search" href="../../search.html" />
    <link rel="next" title="Tutorial metadata" href="tutorial-metadata.html" />
    <link rel="prev" title="Data-flow of tutorial text" href="tutorial-text-dataflow.html" /> 
  </head><body>
<div class="NavBar">
  <a href="../../../app/"><h1>Pytch</h1></a>
  <ul>
    <a href="https://pytch.scss.tcd.ie/"><li>About Pytch</li></a>
    <a href="../../index.html"><li>Help</li></a>
    <a href="../../../app/tutorials/"><li>Tutorials</li></a>
    <a href="../../../app/my-projects/"><li>My projects</li></a>
  </ul>
</div>
<div class="warning-work-in-progress">
  <p>These help pages are incomplete — we are working on it!</p>
</div>
  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body" role="main">
            
  <section id="markdown-processing-within-tutorials">
<h1>Markdown processing within tutorials<a class="headerlink" href="#markdown-processing-within-tutorials" title="Link to this heading">¶</a></h1>
<p>The tutorial system uses Markdown as the source representation of
various pieces of a tutorial:</p>
<ul class="simple">
<li><p>The main tutorial content (in a tutorial’s <code class="docutils literal notranslate"><span class="pre">tutorial.md</span></code> file)</p></li>
<li><p>The tutorial summary (in a tutorial’s <code class="docutils literal notranslate"><span class="pre">summary.md</span></code> file)</p></li>
<li><p>The credits / acknowledgement / licence text for third-party assets
(in commit messages adding or modifying those assets)</p></li>
</ul>
<p>All of these pieces of Markdown are processed by the
<code class="docutils literal notranslate"><span class="pre">soup_from_markdown_text()</span></code> function in:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">pytchbuild</span><span class="o">/</span><span class="n">tutorialcompiler</span><span class="o">/</span><span class="n">fromgitrepo</span><span class="o">/</span><span class="n">tutorial_markdown</span><span class="o">.</span><span class="n">py</span>
</pre></div>
</div>
<p>and returned as a <code class="docutils literal notranslate"><span class="pre">BeautifulSoup</span></code> object.  This is a two-step
process:</p>
<ul class="simple">
<li><p>The <code class="docutils literal notranslate"><span class="pre">markdown</span></code> library turns the Markdown source text into HTML.</p></li>
<li><p>The <code class="docutils literal notranslate"><span class="pre">BeautifulSoup</span></code> library parses that HTML into a Python object
representation.</p></li>
</ul>
<section id="shortcode-processing">
<h2>Shortcode processing<a class="headerlink" href="#shortcode-processing" title="Link to this heading">¶</a></h2>
<p>The <code class="docutils literal notranslate"><span class="pre">markdown</span></code> library allows extensions.  The Pytch
tutorial-compiler installs a <code class="docutils literal notranslate"><span class="pre">BlockProcessor</span></code> extension to handle
our custom shortcodes.</p>
</section>
<section id="fenced-code-blocks">
<h2>Fenced code blocks<a class="headerlink" href="#fenced-code-blocks" title="Link to this heading">¶</a></h2>
<p>The <code class="docutils literal notranslate"><span class="pre">fenced_code</span></code> extension is used to allow the triple-backtick
style of code quoting.  Currently, syntax highlighting is not
performed.  The main usage is in allowing <code class="docutils literal notranslate"><span class="pre">scratch</span></code> as a language,
intended for use with the <a class="reference external" href="https://github.com/scratchblocks/scratchblocks">scratchblocks library</a> in the front-end.</p>
</section>
</section>


            <div class="clearer"></div>
          </div>
        </div>
      </div>
      <div class="sphinxsidebar" role="navigation" aria-label="Main">
        <div class="sphinxsidebarwrapper"><ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../../webapp/user/index.html">Using the Pytch web app</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../vm/user/index.html">Writing Pytch programs</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../about.html">About Pytch</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../contact.html">Contact</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="../../developer.html">Developer documentation</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="../../developer/development-setup.html">Development setup</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../developer/design-overview.html">Design overview</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../vm/developer/index.html">VM</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../webapp/developer/index.html">Webapp</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../medialib/developer/index.html">Media library</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../developer/index.html">Website</a></li>
<li class="toctree-l2 current"><a class="reference internal" href="../index.html">Tools</a><ul class="current">
<li class="toctree-l3 current"><a class="reference internal" href="../index.html#tutorial-compiler-and-related-tools">Tutorial compiler and related tools</a></li>
<li class="toctree-l3"><a class="reference internal" href="../index.html#assembly-of-website-bundle">Assembly of website bundle</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="../../source-build.html">Source and build information</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../releases/changelog.html">Changelog</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../legal/index.html">Legal information</a></li>
</ul>
<div class="docs-home-link"><hr>
  <ul>
    <li>
      <a href="../../index.html">Pytch help home</a>
    <li>
  </ul>
</div>
        </div>
      </div>
      <div class="clearer"></div>
    </div>
  </body>
</html>